---
title: 人机协作 (HITL)
description: 理解 HITL - 为 AI 工作流添加人工监督
---

人机协作（HITL）为 AI 智能体工作流提供人工监督和控制，包括审批机制、参数修改和质量保证。

## 什么是 HITL？

langcrew 中的 HITL 提供战略控制点，让人类可以：

- **批准或拒绝** 工具执行
- **修改参数** 在工具执行前
- **审查和编辑** 工具执行后的结果
- **实施安全策略** 用于生产环境

## 核心架构

HITL 基于 [LangGraph 的原生中断系统](https://langchain-ai.github.io/langgraph/concepts/human_in_the_loop/)，增强了审批工作流：

```python
from langcrew.hitl import HITLConfig

# 基本配置
hitl_config = HITLConfig(
    interrupt_before_tools=["file_write", "database_query"],
    interrupt_after_tools=["data_analysis"]
)
```

## 执行模式

LangCrew 支持两种执行模式，决定哪些中断有效：

| 模式 | 何时使用 | 有效中断 | 忽略的中断 |
|------|---------|---------|-----------|
| **任务模式** | 同时提供 `agents` 和 `tasks` | `interrupt_before_tasks`<br/>`interrupt_after_tasks` | `interrupt_before_agents`<br/>`interrupt_after_agents` |
| **智能体模式** | 只提供 `agents`（无 tasks） | `interrupt_before_agents`<br/>`interrupt_after_agents` | `interrupt_before_tasks`<br/>`interrupt_after_tasks` |

**重要**：工具级和节点级中断在两种模式下都有效。

## 六种中断类型

### 1. 任务级中断

#### interrupt_before_tasks
**有效范围**：仅任务模式

在特定任务执行前暂停以审查或修改任务输入：

```python
from langcrew import Crew, HITLConfig

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    hitl=HITLConfig(
        interrupt_before_tasks=["research_task"]  # 研究开始前审查
    )
)
```

#### interrupt_after_tasks
**有效范围**：仅任务模式

在特定任务完成后暂停以审查或修改输出：

```python
hitl=HITLConfig(
    interrupt_after_tasks=["research_task"]  # 审查研究结果
)
```

### 2. 智能体级中断

#### interrupt_before_agents
**有效范围**：仅智能体模式

在特定智能体执行前暂停：

```python
crew = Crew(
    agents=[coordinator, specialist],  # 无任务 - 智能体模式
    hitl=HITLConfig(
        interrupt_before_agents=["specialist"]  # 专家运行前批准
    )
)
```

#### interrupt_after_agents
**有效范围**：仅智能体模式

在特定智能体完成工作后暂停：

```python
hitl=HITLConfig(
    interrupt_after_agents=["coordinator"]  # 审查协调员的决策
)
```

### 3. 工具级中断

#### interrupt_before_tools
**有效范围**：两种模式

在特定工具执行前暂停（最常用于敏感操作）：

```python
hitl=HITLConfig(
    interrupt_before_tools=["send_email", "make_payment", "delete_file"]
)
```

#### interrupt_after_tools
**有效范围**：两种模式（有会话限制）

在特定工具完成后暂停以审查结果：

```python
hitl=HITLConfig(
    interrupt_after_tools=["data_analysis"]  # 审查分析结果
)
```

:::caution[会话限制]
`interrupt_after_tools` 仅在单个执行会话内有效，工作流重启后无法从中断点恢复。
:::

### 4. 节点级中断

#### interrupt_before_nodes / interrupt_after_nodes
**有效范围**：两种模式

在特定 LangGraph 节点暂停以进行工作流级控制：

```python
hitl=HITLConfig(
    interrupt_before_nodes=["decision_node"],
    interrupt_after_nodes=["processing_node"]
)
```

## 关键组件

### HITLConfig

统一配置所有中断和审批设置。

#### 配置参数

| 参数 | 类型 | 描述 | 默认值 |
|------|------|------|--------|
| `interrupt_before_tasks` | List[str] | 前置中断的任务（仅任务模式） | [] |
| `interrupt_after_tasks` | List[str] | 后置中断的任务（仅任务模式） | [] |
| `interrupt_before_agents` | List[str] | 前置中断的智能体（仅智能体模式） | [] |
| `interrupt_after_agents` | List[str] | 后置中断的智能体（仅智能体模式） | [] |
| `interrupt_before_tools` | List[str] | 执行前需要审批的工具 | [] |
| `interrupt_after_tools` | List[str] | 执行后需要审查的工具 | [] |
| `interrupt_before_nodes` | List[str] | 前置中断的节点 | [] |
| `interrupt_after_nodes` | List[str] | 后置中断的节点 | [] |

### 工具级中断

通过人工审批工作流控制工具执行。

```python
# 在特定工具前/后中断
hitl_config = HITLConfig(
    interrupt_before_tools=["file_write", "web_search"],
    interrupt_after_tools=["data_analysis"]
)
```

- **前置中断**：参数审批和修改
- **后置中断**：结果审查和编辑

:::caution[会话级别限制]
**`interrupt_after_tools` 仅在单个执行会话内有效。** 中断发生在工具节点执行过程中，在下一个检查点保存之前。工作流重启后，系统无法从中断点恢复，必须从最后一个检查点重新开始，可能导致工具重复执行。

对于需要跨重启进行执行后审查的工具，请考虑：

- 对关键操作使用 `interrupt_before_tools`
- 实现支持多次审查周期的可重入工具
- 使用节点级中断进行工作流级别的控制点

:::

### 节点级中断

与 [LangGraph 原生中断系统](https://langchain-ai.github.io/langgraph/concepts/human_in_the_loop/) 的集成，用于工作流控制。

```python
# 在特定工作流节点前/后中断
hitl_config = HITLConfig(
    interrupt_before_nodes=["decision_node"],
    interrupt_after_nodes=["validation_node"]
)
```

节点级中断为工作流执行提供精细控制，允许在智能体工作流的特定决策点或验证步骤进行人工干预。

### UserInputTool

用于智能体主动请求输入的动态用户交互工具。

```python
from langcrew_tools.hitl import UserInputTool

# 智能体可在执行过程中请求用户输入
user_input_tool = UserInputTool()
agent = Agent(tools=[user_input_tool, ...])
```

使智能体能够在工作流执行期间动态收集用户信息。

## 与 langcrew 的集成

HITL 与所有 langcrew 组件无缝集成：

- **[智能体](/zh/concepts/agents)**：为智能体工具添加审批工作流
- **[任务](/zh/concepts/tasks)**：任务从其分配的智能体继承 HITL 设置
- **[团队](/zh/concepts/crews)**：在团队中应用统一的 HITL 策略

```python
# HITL 在智能体级别配置
agent = Agent(
    role="数据分析师", 
    tools=[web_search, file_write],
    hitl=HITLConfig(interrupt_before_tools=["file_write"])
)

# 任务自动从其智能体继承 HITL 设置
task = Task(
    agent=agent,
    description="分析数据并保存报告"
)

# 团队也可以对所有智能体应用 HITL 策略
crew = Crew(
    agents=[agent], 
    tasks=[task],
    hitl=HITLConfig(interrupt_before_tools=["web_search"])
)
```

## 中断类型

### 前置中断

```python
# 用户在执行前批准/修改参数
hitl_config = HITLConfig(
    interrupt_before_tools=["web_search", "file_write"]
)
```

### 后置中断

```python
# 用户在执行后审查/编辑结果
hitl_config = HITLConfig(
    interrupt_after_tools=["data_analysis", "report_generator"]
)
```

## 何时使用 HITL

- **生产环境** 需要人工监督
- **敏感操作** 如文件修改或 API 调用
- **质量保证** 需要人工验证的工作流
- **合规场景** 需要审计跟踪

## 多语言支持

HITL 提供内置的多语言界面支持：

```python
# 自动语言检测
# 当前支持的语言：
# 英文: "approve", "deny", "yes", "no"
# 中文: "批准", "拒绝", "同意", "不同意"
# 未来可以添加更多语言
```

## 下一步

继续学习 [工具系统](/concepts/tools) - 理解如何通过工具扩展智能体能力。
